home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / isres.zip / ISRES.DOC < prev    next >
Text File  |  1990-01-19  |  6KB  |  140 lines
  1. ISRES - Routines to determine if a program is already resident
  2. --------------------------------------------------------------
  3. Brian Foley
  4. TurboPower Software
  5. 1/90
  6. Version 1.0
  7. Released to the public domain
  8.  
  9. Overview
  10. ----------------------------------------------------------------------------
  11.  
  12. The main purpose of ISRES is to provide a facility for non-resident programs
  13. similar to TPTSR/OPTSR's standard module interface. That is, it provides
  14. routines that allow a program to determine if it is being loaded for a
  15. second time. The typical use for ISRES is in a program that allows other
  16. programs to be executed, and needs to prevent the user from loading a second
  17. copy of the same program. The supplied example program, RESTEST, illustrates
  18. the use of ISRES in such a case.
  19.  
  20. A secondary use of ISRES is to provide a communication channel between
  21. programs. When you call ISRES's Install routine, you can specify a pointer
  22. to a data structure or routine that might be of interest to other programs.
  23. This hook can be used to allow other programs access to a program's data, by
  24. passing Install the address of that data. Or it can be used to allow other
  25. programs to call a special routine, by passing Install the address of that
  26. routine.
  27.  
  28. When using the hook for the latter purpose, keep in mind that the routine in
  29. question must either 1) be compiled FAR or 2) be of type interrupt. If the
  30. routine is *not* of type interrupt, it cannot refer to any data stored in
  31. the data segment unless it sets up the DS register first. Practically
  32. speaking, this means that the routine must be written in assembly language.
  33. If the procedure *is* of type interrupt, the DS register will be set up
  34. automatically, so the routine may refer to global data.
  35.  
  36. If you plan to use this hook to store the address of a procedure of type
  37. interrupt, we suggest that you read about the standard module interface in
  38. OPTSR (see Object Professional manual) or TPTSR (see Turbo Professional
  39. manual). The technique you would need to employ, described there, basically
  40. involves using ISRES's IsLoaded routine to retrieve the address of the
  41. procedure, and OPINT/TPINT's EmulateInt to call it.
  42.  
  43. ISRES and TPTSR/OPTSR/OPSWAP
  44. ----------------------------------------------------------------------------
  45.  
  46. The technique used by ISRES to track down other programs is essentially
  47. identical to that used by OPTSR, OPSWAP (also part of Object Professional),
  48. and TPTSR. Consequently, you can use ISRES to locate a TSR that has called
  49. InstallModule and, conversely, a TSR can use either ModuleInstalled or
  50. ModulePtrByName to locate a non-resident program that uses ISRES. For
  51. example, a program using ISRES could locate SMACS by executing the statement
  52.  
  53.   SmacsIsLoaded := IsLoaded('SUPER MACS', P);
  54.  
  55. If SMACS is found, P will contain the address of SMAC'ss command entry
  56. routine. Similarly, if a non-resident program using ISRES had executed the
  57. statement
  58.  
  59.   InstallModule('MYPROG', @MyData);
  60.  
  61. then a TSR could obtain the address of MyData by executing
  62.  
  63.   const
  64.     MyProgName : string[6] = 'MYPROG';
  65.   var
  66.     MyProgIfc : IfcPtr;
  67.     MyDataPtr : Pointer;
  68.   begin
  69.     ...
  70.     MyProgIfc := ModulePtrByName(MyProgName);
  71.     if MyProgIfc = nil then
  72.       {MYPROG not found}
  73.     else
  74.       MyDataPtr := MyProgIfc^.CmdEntryPtr;
  75.     ...
  76.   end.
  77.  
  78. The important distinction to keep in mind here is that the pointer returned
  79. by IsLoaded (if IsLoaded is True) is identical to the address passed to
  80. Install (ISRES) or InstallModule (TPTSR/OPTSR/OPSWAP1). The pointer returned
  81. by ModulePtrByName is the address of an IfcRecord (a record structure
  82. defined by TPTSR/OPTSR/OPSWAP1). To obtain the address of a TSR's command
  83. entry routine or a non-resident program's UserHook, you must look at the
  84. CmdEntryPtr field in the IfcRecord.
  85.  
  86. ISRES and OPEXEC/EXECSWAP
  87. ----------------------------------------------------------------------------
  88.  
  89. ISRES is designed to allow it to be used in conjunction with the OPEXEC unit
  90. in Object Professional, as well as the earlier EXECSWAP unit available on
  91. CompuServe and elsewhere. That is, all of its data is stored in its code
  92. segment, not in the data segment or on the heap. To use the two units (ISRES
  93. and OPEXEC/EXECSWAP) together successfully, however, you must be certain
  94. that ISRES appears *after* the other unit in the main program's USES list.
  95. This insures that all of ISRES's code will remain resident in memory after
  96. the bulk of the program has been swapped to disk or EMS.
  97.  
  98. Interfaced Declarations and Routines
  99. ----------------------------------------------------------------------------
  100.  
  101. ISRES interfaces the following types and routines:
  102.  
  103. type
  104.   ProgramName = string[8];
  105.  
  106.   Name of a program to be installed. Note the limit of 8 characters.
  107.  
  108. procedure Install(Name : ProgramName; UserHook : Pointer);
  109.  
  110.   Adds the specified program to a linked list of installed programs.
  111.   UserHook, if not nil, should point to a procedure or data structure of
  112.   potential interest to other programs. Does nothing if Name is empty.
  113.  
  114. function IsLoaded(Name : String; var UserHook : Pointer) : Boolean;
  115.  
  116.   This routine searches the linked list of installed programs looking for
  117.   Name. If the program is found, IsLoaded will return True, and UserHook
  118.   will contain the pointer that was passed to Install when the program went
  119.   resident. The search is case-sensitive: 'MyProg' is not the same as
  120.   'MYPROG'. Note that Name may be longer than 8 characters: this allows
  121.   IsLoaded to locate TSRs written with TPTSR, OPTSR, or OPSWAP.
  122.  
  123. procedure Uninstall;
  124.  
  125.   Removes the current program, if already installed, from the linked list of
  126.   installed programs.
  127.  
  128. procedure Init16;
  129.  
  130.   Install ISRES's INT $16 handler. This routine is called automatically when
  131.   the program begins, and normally does not need to be called thereafter. It
  132.   should be called only if Restore16 has previously been called.
  133.  
  134. procedure Restore16;
  135.  
  136.   Restore the INT $16 vector grabbed by Init16. This routine is called
  137.   automatically when the program ends, and normally does not need to be
  138.   called directly. It is interfaced only to allow the INT $16 vector to be
  139.   given back temporarily. It can be regrabbed by calling Init16.
  140.